home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 November: Tool Chest / Dev.CD Nov 96 TC / Dev.CD Nov 96 TC.toast / What's New? / Development Kits / Apple Game Sprockets / NetSprocket 1.0.1 / NetSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-12  |  13.5 KB  |  565 lines  |  [TEXT/CWIE]
  1. /*
  2.  *    File:            NetSprocket.h
  3.  *
  4.  *    Version:        Apple Game Sprockets 1.0
  5.  *
  6.  *    Dependencies:    Universal Interfaces 2.1.2 on ETO #20
  7.  *                    Open Transport interfaces 1.1
  8.  *
  9.  *    Contents:        Public interfaces for NetSprocket.
  10.  *
  11.  *    Bugs:            If you find a problem with this file or NetSprocketLib,
  12.  *                    please send e-mail describing the problem in enough detail
  13.  *                    to be reproduced, and include the version number above, the
  14.  *                    version of MacOS and hardware configuration information to
  15.  *                    sprockets@adr.apple.com.
  16.  *
  17.  *    Copyright (c) 1996 Apple Computer, Inc.  All rights reserved.
  18.  */
  19.  
  20. #ifndef __NETSPROCKET__
  21. #define __NETSPROCKET__
  22.  
  23. #ifndef __TYPES__
  24. #include <Types.h>
  25. #endif
  26.  
  27. #ifndef __EVENTS__
  28. #include <Events.h>
  29. #endif
  30.  
  31. #ifndef __OPENTRANSPORT__
  32. #include <OpenTransport.h>
  33. #endif
  34.  
  35. #ifndef __OPENTPTINTERNET__
  36. #include <OpenTptInternet.h>
  37. #endif
  38.  
  39.  
  40. #if GENERATINGPOWERPC
  41.  
  42. #if PRAGMA_ALIGN_SUPPORTED
  43. #pragma options align=power
  44. #endif
  45.  
  46. #define kNSpMaxPlayerNameLen        31
  47. #define kNSpMaxGroupNameLen            31
  48. #define kNSpMaxPasswordLen            31
  49. #define kNSpMaxGameNameLen            31
  50. #define kNSpMaxDefinitionStringLen    255
  51.  
  52.  
  53. /* NetSprocket basic types */
  54. typedef    struct NSpGamePrivate        *NSpGameReference;
  55. typedef    struct NSpProtocolPrivate    *NSpProtocolReference;
  56. typedef    struct NSpListPrivate        *NSpProtocolListReference;
  57. typedef struct NSPAddressPrivate    *NSpAddressReference;
  58. typedef SInt32                        NSpEventCode;
  59. typedef    SInt32                        NSpGameID;
  60. typedef    SInt32                        NSpPlayerID;
  61. typedef NSpPlayerID                    NSpGroupID;
  62. typedef UInt32                        NSpPlayerType;
  63. typedef SInt32                        NSpFlags;
  64.  
  65. /* Individual player info */
  66. typedef struct NSpPlayerInfo
  67. {
  68.     NSpPlayerID        id;
  69.     NSpPlayerType    type;
  70.     Str31            name;
  71.     UInt32            groupCount;
  72.     NSpGroupID        groups[kVariableLengthArray];
  73. } NSpPlayerInfo, *NSpPlayerInfoPtr;
  74.  
  75.     
  76. /* list of all players */
  77. typedef struct NSpPlayerEnumeration
  78. {
  79.     UInt32                count;
  80.     NSpPlayerInfoPtr    playerInfo[kVariableLengthArray];
  81. } NSpPlayerEnumeration, *NSpPlayerEnumerationPtr;
  82.  
  83.  
  84. /* Individual group info */
  85. typedef struct NSpGroupInfo
  86. {
  87.     NSpGroupID    id;
  88.     UInt32        playerCount;
  89.     NSpPlayerID    players[kVariableLengthArray];
  90. } NSpGroupInfo, *NSpGroupInfoPtr;
  91.  
  92.  
  93. /* List of all groups */
  94. typedef struct NSpGroupEnumeration
  95. {
  96.     UInt32            count;
  97.     NSpGroupInfoPtr    groups[kVariableLengthArray];
  98. } NSpGroupEnumeration, *NSpGroupEnumerationPtr;
  99.  
  100. /* Topology types */
  101. typedef UInt32 NSpTopology;
  102. enum
  103. {
  104.     kNSpClientServer =     0x00000001
  105. };
  106.  
  107. /* Game information */
  108. typedef struct NSpGameInfo
  109. {
  110.     UInt32        maxPlayers;
  111.     UInt32        currentPlayers;
  112.     UInt32        currentGroups;
  113.     NSpTopology    topology;
  114.     UInt32        reserved;
  115.     Str31        name;
  116.     Str31        password;
  117. } NSpGameInfo;
  118.     
  119.     
  120. /* Structure used for sending and receiving network messages */
  121. typedef struct NSpMessageHeader
  122. {
  123.     UInt32        version;    /* Used by NetSprocket.  Don't touch this */
  124.     SInt32        what;        /* The kind of message (e.g. player joined) */
  125.     NSpPlayerID    from;        /* ID of the sender */
  126.     NSpPlayerID    to;            /* (player or group) id of the intended recipient */
  127.     UInt32        id;            /* Unique ID for this message & (from) player */
  128.     UInt32        when;        /* Timestamp for the message */
  129.     UInt32        messageLen;    /* Bytes of data in the entire message (including the header) */
  130. } NSpMessageHeader;
  131.  
  132.  
  133. /* NetSprocket-defined message structures */
  134.  
  135. typedef struct NSpErrorMessage
  136. {
  137.     NSpMessageHeader    header;
  138.     OSStatus            error;
  139. } NSpErrorMessage;
  140.  
  141.  
  142. typedef struct NSpJoinRequestMessage
  143. {
  144.     NSpMessageHeader    header;
  145.     Str31                name;
  146.     Str31                password;
  147.     UInt32                type;
  148.     UInt32                customDataLen;
  149.     UInt8                customData[kVariableLengthArray];
  150. } NSpJoinRequestMessage;
  151.  
  152.  
  153. typedef struct NSpJoinApprovedMessage
  154. {
  155.     NSpMessageHeader    header;
  156. } NSpJoinApprovedMessage;
  157.  
  158.  
  159. typedef struct NSpJoinDeniedMessage
  160. {
  161.     NSpMessageHeader    header;
  162.     Str255                reason;
  163. } NSpJoinDeniedMessage;
  164.  
  165.  
  166. typedef struct NSpPlayerJoinedMessage
  167. {
  168.     NSpMessageHeader    header;
  169.     UInt32                playerCount;
  170.     NSpPlayerInfo            playerInfo;    
  171. } NSpPlayerJoinedMessage;
  172.  
  173.  
  174. typedef struct NSpPlayerLeftMessage
  175. {
  176.     NSpMessageHeader    header;
  177.     UInt32                playerCount;
  178.     NSpPlayerID            playerID;    
  179. } NSpPlayerLeftMessage;
  180.  
  181. typedef struct NSpHostChangedMessage
  182. {
  183.     NSpMessageHeader    header;
  184.     NSpPlayerID            newHost;
  185. } NSpHostChangedMessage;
  186.  
  187.  
  188. typedef struct NSpGameTerminatedMessage
  189. {
  190.     NSpMessageHeader    header;
  191. } NSpGameTerminatedMessage;
  192.  
  193.  
  194. /* Different kinds of messages.  These can NOT be bitwise ORed together */
  195. enum
  196. {
  197.     kNSpSendFlag_Junk =         0x00100000,        /* will be sent (try once) when there is nothing else pending */
  198.     kNSpSendFlag_Normal =         0x00200000,        /* will be sent immediately (try once) */
  199.     kNSpSendFlag_Registered =     0x00400000        /* will be sent immediately (guaranteed, in order) */
  200. };
  201.  
  202.  
  203. /* Options for message delivery.  These can be bitwise ORed together with each other,
  204.         as well as with ONE of the above */
  205. enum 
  206. {
  207.     kNSpSendFlag_FailIfPipeFull =     0x00000001,
  208.     kNSpSendFlag_SelfSend =         0x00000002,
  209.     kNSpSendFlag_Blocking =         0x00000004
  210. };
  211.  
  212.  
  213. /* Options for Hosting Joining, and Deleting games */
  214. enum
  215. {
  216.     kNSpGameFlag_DontAdvertise            =    0x00000001,
  217.     kNSpGameFlag_ForceTerminateGame     =     0x00000002
  218. };
  219.  
  220. /* Message "what" types */
  221. /* Apple reserves all negative "what" values (anything with bit 32 set) */ 
  222. enum 
  223. {
  224.     kNSpSystemMessagePrefix = 0x80000000,
  225.     kNSpError =                 kNSpSystemMessagePrefix | 0x7FFFFFFF,
  226.     kNSpJoinRequest =         kNSpSystemMessagePrefix | 0x00000001,
  227.     kNSpJoinApproved =         kNSpSystemMessagePrefix | 0x00000002,
  228.     kNSpJoinDenied =         kNSpSystemMessagePrefix | 0x00000003,
  229.     kNSpPlayerJoined =         kNSpSystemMessagePrefix | 0x00000004,
  230.     kNSpPlayerLeft =         kNSpSystemMessagePrefix | 0x00000005,
  231.     kNSpHostChanged =         kNSpSystemMessagePrefix | 0x00000006,
  232.     kNSpGameTerminated=     kNSpSystemMessagePrefix | 0x00000007
  233. };
  234.  
  235.  
  236. /* Special TPlayerIDs  for sending messages */
  237. enum
  238. {
  239.     kNSpAllPlayers =     0x00000000,
  240.     kNSpHostOnly =        0xFFFFFFFF
  241. };
  242.     
  243.  
  244. #ifdef __cplusplus
  245. extern "C" {
  246. #endif
  247.  
  248. /************************  Initialization  ************************/
  249.  
  250. OSStatus NSpInitialize(
  251.     UInt32                         inStandardMessageSize, 
  252.     UInt32                         inBufferSize, 
  253.     UInt32                         inQElements, 
  254.     NSpGameID                     inGameID, 
  255.     UInt32                         inTimeout);
  256.  
  257.  
  258. /**************************  Protocols  **************************/
  259.  
  260. /* Programmatic protocol routines */
  261. OSStatus NSpProtocol_New(
  262.     const char*                 inDefinitionString, 
  263.     NSpProtocolReference*        outReference);
  264.  
  265. void NSpProtocol_Dispose(
  266.     NSpProtocolReference         inProtocolRef);
  267.  
  268. OSStatus NSpProtocol_ExtractDefinitionString(
  269.     NSpProtocolReference         inProtocolRef, 
  270.     char*                        outDefinitionString);
  271.  
  272.  
  273. /* Protocol list routines */
  274. OSStatus NSpProtocolList_New(
  275.     NSpProtocolReference         inProtocolRef,
  276.     NSpProtocolListReference*    outList);
  277.  
  278. void NSpProtocolList_Dispose(
  279.     NSpProtocolListReference     inProtocolList);
  280.  
  281. OSStatus NSpProtocolList_Append(
  282.     NSpProtocolListReference     inProtocolList,
  283.     NSpProtocolReference         inProtocolRef);
  284.  
  285. OSStatus NSpProtocolList_Remove(
  286.     NSpProtocolListReference     inProtocolList, 
  287.     NSpProtocolReference         inProtocolRef);
  288.  
  289. OSStatus NSpProtocolList_RemoveIndexed(
  290.     NSpProtocolListReference     inProtocolList,
  291.     UInt32                         inIndex);
  292.  
  293. UInt32 NSpProtocolList_GetCount(
  294.     NSpProtocolReference         inProtocolList);
  295.  
  296. NSpProtocolReference NSpProtocolList_GetIndexedRef(
  297.     NSpProtocolListReference     inProtocolList,
  298.     UInt32                         inIndex);
  299.  
  300.  
  301. /* Helpers */
  302. NSpProtocolReference NSpProtocol_CreateAppleTalk(
  303.     ConstStr31Param             inNBPName,
  304.     ConstStr31Param             inNBPType, 
  305.     UInt32                         inMaxRTT,
  306.     UInt32                         inMinThruput);
  307.  
  308. NSpProtocolReference NSpProtocol_CreateIP(
  309.     InetPort                     inPort,
  310.     UInt32                         inMaxRTT,
  311.     UInt32                         inMinThruput);
  312.  
  313.  
  314. /***********************  Human Interface  ************************/
  315. typedef pascal Boolean (*NSpEventProcPtr) (EventRecord* inEvent);
  316.  
  317.  
  318. NSpAddressReference NSpDoModalJoinDialog(
  319.     ConstStr31Param             inGameType, 
  320.     ConstStr255Param             inEntityListLabel,
  321.     Str31                         ioName, 
  322.     Str31                         ioPassword, 
  323.     NSpEventProcPtr             inEventProcPtr);
  324.  
  325. Boolean NSpDoModalHostDialog(
  326.     NSpProtocolListReference     ioProtocolList, 
  327.     Str31                         ioGameName, 
  328.     Str31                         ioPlayerName,
  329.     Str31                         ioPassword, 
  330.     NSpEventProcPtr             inEventProcPtr);
  331.  
  332.  
  333. /*********************  Hosting and Joining  **********************/
  334.  
  335. OSStatus NSpGame_Host(
  336.     NSpGameReference*            outGame, 
  337.     NSpProtocolListReference     inProtocolList, 
  338.     UInt32                         inMaxPlayers, 
  339.     ConstStr31Param             inGameName, 
  340.     ConstStr31Param             inPassword,
  341.     ConstStr31Param             inPlayerName, 
  342.     NSpPlayerType                 inPlayerType, 
  343.     NSpTopology                 inTopology,
  344.     NSpFlags                     inFlags);
  345.  
  346. OSStatus NSpGame_Join(
  347.     NSpGameReference*            outGame, 
  348.     NSpAddressReference         inAddress, 
  349.     ConstStr31Param             inName,
  350.     ConstStr31Param             inPassword,
  351.     NSpPlayerType                 inType, 
  352.     void*                        inCustomData,
  353.     UInt32                         inCustomDataLen,  
  354.     NSpFlags                     inFlags);
  355.  
  356. OSStatus NSpGame_EnableAdvertising(
  357.     NSpGameReference             inGame, 
  358.     NSpProtocolReference         inProtocol, 
  359.     Boolean                     inEnable);
  360.  
  361. OSStatus NSpGame_Dispose(
  362.     NSpGameReference             inGame, 
  363.     NSpFlags                     inFlags);
  364.  
  365.  
  366. /**************************  Messaging  **************************/
  367.  
  368. OSStatus NSpMessage_Send(
  369.     NSpGameReference             inGame, 
  370.     NSpMessageHeader*            inMessage, 
  371.     NSpFlags                     inFlags);
  372.  
  373. NSpMessageHeader *NSpMessage_Get(
  374.     NSpGameReference             inGame);
  375.  
  376. void NSpMessage_Release(
  377.     NSpGameReference             inGame, 
  378.     NSpMessageHeader*            inMessage);
  379.  
  380. /* Helpers */
  381. OSStatus NSpMessage_SendTo(
  382.     NSpGameReference             inGame,
  383.     NSpPlayerID                    inTo,
  384.     SInt32                        inWhat, 
  385.     void*                        inData,
  386.     UInt32                        inDataLen, 
  387.     NSpFlags                     inFlags);
  388.     
  389.  
  390. /*********************  Player Information  **********************/
  391.  
  392. NSpPlayerID NSpPlayer_GetMyID(
  393.     NSpGameReference             inGame);
  394.  
  395. OSStatus NSpPlayer_GetInfo(
  396.     NSpGameReference             inGame, 
  397.     NSpPlayerID                 inPlayerID, 
  398.     NSpPlayerInfoPtr*            outInfo);
  399.  
  400. void NSpPlayer_ReleaseInfo(
  401.     NSpGameReference             inGame, 
  402.     NSpPlayerInfoPtr             inInfo);
  403.  
  404. OSStatus NSpPlayer_GetEnumeration(
  405.     NSpGameReference             inGame, 
  406.     NSpPlayerEnumerationPtr*    outPlayers);
  407.  
  408. void NSpPlayer_ReleaseEnumeration(
  409.     NSpGameReference             inGame, 
  410.     NSpPlayerEnumerationPtr     inPlayers);
  411.  
  412. UInt32 NSpPlayer_GetRoundTripTime(
  413.     NSpGameReference             inGame, 
  414.     NSpPlayerID                 inPlayer); 
  415.  
  416. UInt32 NSpPlayer_GetThruput(
  417.     NSpGameReference             inGame, 
  418.     NSpPlayerID                 inPlayer); 
  419.  
  420.  
  421. /*********************  Group Management  **********************/
  422.  
  423. OSStatus NSpGroup_New(
  424.     NSpGameReference             inGame, 
  425.     NSpGroupID*                    outGroupID);
  426.  
  427. OSStatus NSpGroup_Dispose(
  428.     NSpGameReference             inGame, 
  429.     NSpGroupID                     inGroupID);
  430.  
  431. OSStatus NSpGroup_AddPlayer(
  432.     NSpGameReference             inGame, 
  433.     NSpGroupID                     inGroupID, 
  434.     NSpPlayerID                 inPlayerID);
  435.  
  436. OSStatus NSpGroup_RemovePlayer(
  437.     NSpGameReference             inGame, 
  438.     NSpGroupID                     inGroupID,
  439.     NSpPlayerID                 inPlayerID);
  440.  
  441. OSStatus NSpGroup_GetInfo(
  442.     NSpGameReference             inGame, 
  443.     NSpGroupID                     inGroupID, 
  444.     NSpGroupInfoPtr*            outInfo);
  445.  
  446. void NSpGroup_ReleaseInfo(
  447.     NSpGameReference             inGame, 
  448.     NSpGroupInfoPtr             inInfo);
  449.  
  450. OSStatus NSpGroup_GetEnumeration(
  451.     NSpGameReference             inGame, 
  452.     NSpGroupEnumerationPtr*        outGroups);
  453.  
  454. void NSpGroup_ReleaseEnumeration(
  455.     NSpGameReference             inGame, 
  456.     NSpGroupEnumerationPtr         inGroups);
  457.  
  458.  
  459. /**************************  Utilities  ***************************/
  460.  
  461. void NSpClearMessageHeader(
  462.     NSpMessageHeader*            inMessage);
  463.  
  464. UInt32 NSpGetCurrentTimeStamp(
  465.     NSpGameReference             inGame);
  466.  
  467. NSpAddressReference    NSpConvertOTAddrToAddressReference(
  468.     OTAddress*                    inAddress);
  469.  
  470. OTAddress *NSpConvertAddressReferenceToOTAddr(
  471.     NSpAddressReference         inAddress);
  472.  
  473. void NSpReleaseAddressReference(
  474.     NSpAddressReference         inAddress);
  475.  
  476.  
  477. /************************ Advanced/Async routines ****************/
  478.  
  479. typedef pascal void (*NSpCallbackProcPtr)(
  480.     NSpGameReference             inGame, 
  481.     void*                         inContext, 
  482.     NSpEventCode                 inCode, 
  483.     OSStatus                     inStatus, 
  484.     void*                         inCookie);
  485.  
  486. OSStatus NSpInstallCallbackHandler(
  487.     NSpCallbackProcPtr             inHandler, 
  488.     void*                        inContext);
  489.  
  490.  
  491. typedef pascal Boolean (*NSpJoinRequestHandlerProcPtr)(
  492.     NSpGameReference             inGame, 
  493.     NSpJoinRequestMessage*        inMessage, 
  494.     void*                         inContext,
  495.     Str255                        outReason);
  496.  
  497. OSStatus NSpInstallJoinRequestHandler(
  498.     NSpJoinRequestHandlerProcPtr inHandler, 
  499.     void*                        inContext);
  500.  
  501.  
  502. typedef pascal Boolean (*NSpMessageHandlerProcPtr)(
  503.     NSpGameReference             inGame, 
  504.     NSpMessageHeader*            inMessage, 
  505.     void*                         inContext);
  506.  
  507. OSStatus NSpInstallAsyncMessageHandler(
  508.     NSpMessageHandlerProcPtr     inHandler, 
  509.     void*                        inContext);
  510.  
  511.  
  512.  
  513.  
  514. #ifdef __cplusplus
  515. }
  516. #endif
  517.  
  518. /* NetSprocket Error Codes */
  519. enum
  520. {
  521.     kNSpInitializationFailedErr         = -30360,
  522.     kNSpAlreadyInitializedErr             = -30361,
  523.     kNSpTopologyNotSupportedErr         = -30362,
  524.     kNSpPipeFullErr                         = -30364,
  525.     kNSpHostFailedErr                     = -30365,
  526.     kNSpProtocolNotAvailableErr         = -30366,
  527.     kNSpInvalidGameRefErr                 = -30367,
  528.     kNSpInvalidParameterErr             = -30369,
  529.     kNSpOTNotPresentErr                 = -30370,
  530.     kNSpOTVersionTooOldErr                = -30371,
  531.     kNSpMemAllocationErr                 = -30373,
  532.     kNSpAlreadyAdvertisingErr             = -30374,
  533.     kNSpNotAdvertisingErr                 = -30376,
  534.     kNSpInvalidAddressErr                 = -30377,
  535.     kNSpFreeQExhaustedErr                = -30378,
  536.     kNSpRemovePlayerFailedErr            = -30379,
  537.     kNSpAddressInUseErr                    = -30380,
  538.     kNSpFeatureNotImplementedErr        = -30381,
  539.     kNSpNameRequiredErr                 = -30382,
  540.     kNSpInvalidPlayerIDErr                 = -30383,
  541.     kNSpInvalidGroupIDErr                 = -30384,
  542.     kNSpNoPlayersErr                     = -30385,
  543.     kNSpNoGroupsErr                     = -30386,
  544.     kNSpNoHostVolunteersErr             = -30387,
  545.     kNSpCreateGroupFailedErr             = -30388,
  546.     kNSpAddPlayerFailedErr                 = -30389,
  547.     kNSpInvalidDefinitionErr            = -30390,
  548.     kNSpInvalidProtocolRefErr            = -30391,
  549.     kNSpInvalidProtocolListErr            = -30392,
  550.     kNSpTimeoutErr                        = -30393,
  551.     kNSpGameTerminatedErr                = -30394,
  552.     kNSpConnectFailedErr                = -30395,
  553.     kNSpSendFailedErr                    = -30396,
  554.     kNSpJoinFailedErr                    = -30399
  555. };
  556.  
  557.  
  558.  
  559. #if PRAGMA_ALIGN_SUPPORTED
  560. #pragma options align=reset
  561. #endif
  562.  
  563. #endif /* GENERATINGPOWERPC */
  564. #endif /* __NETSPROCKET__ */
  565.